Software Description
Overview
Software for an energy-efficient, LoRaWAN class A, indoor/outdoor asset tracking device capable of performing localization, movement detection and temperature and battery measurement. Based on the FMLR-LR1110 and LBM4 stack.
Main functionality:
- Localization through passive GNSS, WiFi sniffing, LoRa TDoA
- Indoor recognition with fall-back to WiFi sniffing
- Movment detection and configurable steady- and moving-intervals for localization triggering
- Temperature and battery voltage measurement with heartbeat uplink and configurable interval
- Configuration through LoRaWAN downlink
- LED for visual feedback of application state
- EU868/US915 compatibility
State Diagramm
Class Diagram
Features Overview
Features
Functional requirements
F-001: Interval-triggered localization
In absence of movements, localization will be performed after the interval steady_interval_s. After a movmement-triggered localization the interval used to trigger the next interval-triggered localization is moving_interval_s instead.
F-002: Movement-triggered localization
After the detection of a movement, localization is performed. Movements are detected with a LIS2DW accelerometer. The logic for a successfull movement detection is as follows:
- Detected acceleration is greater than the configured threshold acc_threshold for at least the configured delay acc_delay_ms.
After a movement-triggered localization, the interval moving_interval_s is used to trigger the following interval-triggered localization. An hold_timer will ensure that a localization doesn't happen to shortly after the previous one. The hold_timer is set to the minimum between steady_interal_s and moving_interval_s.
F-003: Localization type selection
The device starts by performing a WiFi sniffing. If the number of sniffed WiFi AP is less than minAP, then a pasive GNSS localization is attempted. Otherwise, the device sends the WiFi UL without attempting a GNSS localization.
F-004: Passive GNSS localization
Localization can be performed using passive GNSS. The LoRa Basic Modem geolocation service 'GNSS scan & send' is used for this purpose with the following options:
- MOBILE mode
- GPS & BEIDU
- SEND MODE, i.e. directly send the scan result if valid, no buffering.
The default option is "SEND MODE".
The almanac update is done autonmously, using the GNSS almanac demodulation service available with LR11xx radio chip (i.e. without using LoRa Cloud assistance).
Refer to the LoRa Basic Modem geolocation services documentation for any further detail.
F-005: WiFi sniffing localization
Localization can be performed using WiFi sniffing. The LoRa Basic Modem geolocation service 'WiFi scan & service' is used for this purpose with the following options:
- SEND MODE, i.e. directly send the scan result, no buffering.
Refer to the LoRa Basic Modem geolocation services documentation for any further detail.
F-006: LoRa TDoA localization
Localization can also be performed using LoRa TDoA. This is handled completely in the cloud and no specific action must be performed by the software since any type of localization execution is followed by an uplink, needed in the cloud to perform LoRa TDoA localization.
F-007: Temperature and battery measurement
Temperature and battery voltage are measured every interval heartbeat_interval_h (unit: hours). For the temperature a SHT3X sensor is used. The Battery voltage is inferred by measuring the internal reference voltage of the MCU. Temperature and battery data are sent in the heartbeat uplink.
F-008: Sleep
If the software is not performing localization, movement detection or measurements, the MCU is put to sleep until the next action needs to be executed.
F-009: Configuration parameters
| Parameter | Type | Range | Description | Default value |
|---|---|---|---|---|
| steady_interval_s | UINT16 | 0..65535 | Interval for localization trigger while steady, in seconds | 21600 |
| moving_interval_s | UINT16 | 0..65535 | Interval for localization trigger while moving, in seconds | 3600 |
| temperature_polling_interval_s | UINT16 | 0..65535 | Interval for polling temperature sensor, in seconds | 900 |
| temperature_uplink_hold_interval_s | UINT16 | 0..65535 | Interval for temperature measurement uplink if it is outside of threshold, in seconds | 3600 |
| temperature_upper_threshold | INT8 | -127..128 | Temperature upper threshold to yield uplink from polling in °C | 40 |
| temperature_lower_threshold | INT8 | -127..128 | Temperature lower threshold to yield uplink from polling in °C | -5 |
| heartbeat_interval_h | UINT8 | 0..255 | Interval for temperature and battery measurement and uplink, in hours | 12 |
| acc_threshold_mg | UINT16 | 0..65535 | Accelerometer threshold to start movement detection, in mg | 300 |
| acc_delay_ms | UINT16 | 0..65535 | Acceleration delay for detecting movement, in ms | 1500 |
| flags | UINT8 | See flags description | 00111110 | |
| lic_100_percent | UINT16 | 0..4000 | LIC 100% percentage VCELL voltage in mV | 3800 |
| lic_80_percent | UINT16 | 0..4000 | LIC 80% percentage VCELL voltage in mV | 3650 |
| lic_60_percent | UINT16 | 0..4000 | LIC 60% percentage VCELL voltage in mV | 3500 |
| lic_40_percent | UINT16 | 0..4000 | LIC 40% percentage VCELL voltage in mV | 3250 |
| lic_20_percent | UINT16 | 0..4000 | LIC 20% percentage VCELL voltage in mV | 2850 |
| min_AP | UINT8 | 1..6 | Minimum amount of AP(s) to yield an uplink | 3 |
Flags:
| Bit 7 | Bit 6 | Bit 5 | Bit 4 | Bit 3 | Bits [2:0] |
|---|---|---|---|---|---|
| reserved | reserved | GNSS enable | WiFi sniffing enable | Acc enable | Data rate |
Data rate:
000: DR5 (EU868 SF7),
001: DR4 (EU868 SF8),
010: DR3 (EU868 SF9, US915 SF7) [DEFAULT],
011: DR2 (EU868 SF10, US915 SF8),
100: DR1 (EU868 SF11, US915 SF9),
101: DR0 (EU868 SF12),
110: DR1-3 array (EU868 SF9-11, US915 SF7-9),
111: ADR (SF7-12 for EU868)
Duty cycling is enabled by default to conform with regulations.
F-010: Power states
In case the HW variant with the PV cell, LIC and harvester, different power states are introduced to preserve energy.
Approximate Energy-Based Voltage Levels (for LICs):
| Energy % | Voltage |
|---|---|
| 100% | 3.8V |
| 80% | 3.65V |
| 60% | 3.5V |
| 40% | 3.25V |
| 20% | 2.85V |
| 0% | 2.5V |
Power states:
- Below 20%: Send only 1 Low Power battery uplink per day containing only voltage levels for the VCC and the PV Cell voltage
- Between 20-40%: Normal operation with accelerometer disabled (No location trigger by accelerometer)
- Above 40%: Normal operation
VCC measurement is performed before power-intensive operations, eg. location acquisition, sending uplink, etc.
F-011: LoRaWAN Join procedure
After Power-On the device will attemt to Join the LoRaWAN network with OTAA with a random Spreading Factor.
In case the HW variant with the PV cell, LIC and harvester, the join procedure will not start until the LIC is at least 20% to avoid boot-loop.
Join back-off strategy: (Standard LBMv4 strategy)
- During first hour after first join try => duty cycle of 1/100 ie. 36s over 1 hour
- During the 10 hours following first hour after first join try => duty cycle of 1/1000 ie. 36s over 10 hours
- Following the first 11 hours after first join try => duty cycle of 1/10000 ie. 8.7s over 24 hours
External Interface Requirements
EI-001: Button
The smart label has only one button:
- Press 10 sec to switch off the label
- Press 0.2 sec to switch on (5 green blinks)
EI-002: LED
The LED on SmartLabel is used by the software as follows:
- Power on: 5 consecutive 100ms green blinks
- Join successful: 3 consecutive 100ms green blinks
- Join failed: 3 consecutive 100ms red blinks
EI-003: Radio Specification
The device operates on:
- LoRaWan
- Region EU868, US915
- Version 1.0.4
- Class A
EI-004: Uplinks
Low Power battery uplink
Uplink port: 1
Sent only once a day in case the energy level is below 20%
| Bytes[0:1] | Bytes[2:3] | |
|---|---|---|
| Value | Battery | Cell voltage |
| Size [Bytes] | 2 | 2 |
| Type | UINT16 | UINT16 |
| Unit | mV | mV |
Temperature uplink
Uplink port: 2
Temperature measurement uplink if the temperature is outside of thresholds
| Bytes[0:1] | Byte 2 | |
|---|---|---|
| Value | Temperature | RH |
| Size [Bytes] | 2 | 1 |
| Type | UINT16 | UINT8 |
| Unit | 0.01 C | 0.5 % |
Heartbeat uplink
Uplink port: 11
| Bytes[0:1] | Bytes[2:3] | Bytes[4:5] | Byte 6 | |
|---|---|---|---|---|
| Value | Battery | Cell voltage | Temperature | RH |
| Size [Bytes] | 2 | 2 | 2 | 1 |
| Type | UINT16 | UINT16 | UINT16 | UINT8 |
| Unit | mV | mV | 0.01 C | 0.5 % |
GNSS scan uplink
Uplink port: 192
| Byte 0 | Bytes[1:N] | |
|---|---|---|
| Value | Last of scan group and group token | NAV message |
| Size [Bytes] | 1 | max 49 |
| Type | UINT8 | UINT8 |
WiFi scan uplink
Uplink port: 197
| Byte 0 | Byte 1 | Bytes[2:7] | Byte 8 | Bytes[9:14] | ... | |||
|---|---|---|---|---|---|---|---|---|
| Value | 0x01 | AP1 RSSI | AP1 MAC | AP2 RSSI | AP2 MAC | APN RSSI | APN MAC | |
| Size [Bytes] | 1 | 1 | 6 | 1 | 6 | 1 | 6 | |
| Type | UINT8 | UINT8 | UINT8 | UINT8 | UINT8 | UINT8 | UINT8 |
Configuration uplink
Uplink port: 4
| Byte 0 | Bytes[1:2] | Bytes[3:4] | Byte 5 | Bytes[6:7] | Bytes[8:9] | Bytes[10:11] | Bytes[12:13] | Byte 14 | Byte 15 | Byte 16 | Byte 17 | Byte 18 | Byte 19 | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Value | flags | steady_interval_s | moving_interval_s | heartbeat_interval_h | acc_threshold_mg | acc_delay_ms | temperature_polling_interval_s | temperature_uplink_hold_interval_s | temperature_upper_threshold | temperature_lower_threshold | min_AP | Version_Major* | Version_Minor* | Version_Patch* |
| Size [Bytes] | 1 | 2 | 2 | 1 | 2 | 2 | 2 | 2 | 1 | 1 | 1 | 1 | 1 | 1 |
| Type | UINT8 | UINT16 | UINT16 | UINT8 | UINT16 | UINT16 | UINT16 | UINT16 | INT8 | INT8 | UINT8 | UINT8 | UINT8 | UINT8 |
*Firmware version is only available in the first uplink after reset.
LIC Voltage levels uplink/downlink
Uplink/Downlink port: 150
| Bytes[0:1] | Bytes[2:3] | Bytes[4:5] | Bytes[6:7] | Bytes[8:9] | |
|---|---|---|---|---|---|
| Value | lic_100_percent | lic_80_percent | lic_60_percent | lic_40_percent | lic_20_percent |
| Size [Bytes] | 2 | 2 | 2 | 2 | 2 |
| Type | UINT16 | UINT16 | UINT16 | UINT16 | UINT16 |
| Unit | mV | mV | mV | mV | mV |
EI-005: Downlinks
Configuration downlink
Downlink port: 128
| Byte 0 | Bytes[1:2] | Bytes[3:4] | Byte 5 | Bytes[6:7] | Bytes[8:9] | Bytes[10:11] | Bytes[12:13] | Bytes 14 | Bytes 15 | Bytes 16 | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Value | flags | steady_interval_s | moving_interval_s | heartbeat_interval_h | acc_threshold_mg | acc_delay_ms | temperature_polling_interval_s | temperature_uplink_hold_interval_s | temperature_upper_threshold | temperature_lower_threshold | min_AP |
| Size [Bytes] | 1 | 2 | 2 | 1 | 2 | 2 | 2 | 2 | 1 | 1 | 1 |
| Type | UINT8 | UINT16 | UINT16 | UINT8 | UINT16 | UINT16 | UINT16 | UINT16 | INT8 | INT8 | UINT8 |
In case temperature_polling_interval_s, temperature_uplink_hold_interval_s are set to 0, the function is disabled
Reset downlink
Downlink port: 129
| Byte 0 | |
|---|---|
| Value | 1 |
| Size [Bytes] | 1 |
| Type | UINT8 |
Turn-off downlink
Command to turn the device off. Activation is only possible with button press afterwards. (Press for 0.2 seconds to enable, press for 10 seconds to disable)
Downlink port: 130
| Byte 0 | |
|---|---|
| Value | 1 |
| Size [Bytes] | 1 |
| Type | UINT8 |
Nonfunctional Requirements
NF-001 LoRaWan 1.0.4 Compliant
The software needs to compliant with LoRaWan 1.0.4 Standard and fullfill the certification process